<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<link rel="STYLESHEET" type="text/css" href="./styles.css" /></head>
<body>

<!-- ===================================================================== -->
<!-- = XML information goes here                                         = -->
<!-- ===================================================================== -->
<lzelement title="RPC">
    <lztier>RPC Components</lztier>
    <lzcategory>RPC</lzcategory>
    <lzshortdesc>
        Remote procedure calls.
    </lzshortdesc>
    <lztag>rpc/rpc.xml</lztag>
</lzelement>

<p>The &lt;rpc&gt; tag is the abstract base class for RPC classes. Subclasses
must implement the load() method, which is responsible for creating the proxy
object. The <dfn>proxy</dfn> object contains a set of function stubs that invoke
a remote function (or procedure) over the network. It's up to the caller of the
stub function to know what parameters need to be passed in by looking at what
the backend remote function expects. If calling a JavaRemoting (&lt;javarpc&gt;)
function, looking at the associated Java API will be necessary. If calling a
SOAP (&lt;soap&gt;) function, the developer will need to look at the
corresponding operation in a WSDL file.</p>

<p>The implementation of this class can be found in
lps/components/rpc/rpc.lzx. For details, see the <a href="${dguide}rpc.html">RPC chapter in the Developer's
Guide.</a></p>

<p>Objects derived from rpc us function stubs in the proxy object to invoke a remote function. Each function stub
expects an array of arguments and a delegate to deal with the return value,
respectively. Both the array and the delegate are required. If a function has no arguments, rpc passes in an
empty array.</p>

<example title="Invoking remote function using proxy function stub">
&lt;canvas debug="true" height="280"&gt;

    &lt;debug x="10" y="40" width="470" height="230" /&gt;

    &lt;soap name="temperature" autoload="false"
          wsdl="http://developerdays.com/cgi-bin/tempconverter.exe/wsdl/ITempConverter"&gt;

        &lt;method name="init"&gt;
            super.init();
            Debug.write('soap service loading...');
            this.load();
        &lt;/method&gt;

        &lt;method event="onload"&gt;
            Debug.write('temperature service loaded!');
            Debug.write('---');

            // don't allow others to call RPC object until proxy is loaded.
            canvas.convert.setVisible(true);
        &lt;/method&gt;

    &lt;/soap&gt;

    &lt;button name="convert" text="convert" x="10" y="10" visible="false"&gt;

        &lt;attribute name="myDel" 
                   value="$once{new LzDelegate(this, 'myhandler')}" /&gt;

        &lt;method event="onclick"&gt;
            var f = 100;
            <em>canvas.temperature.proxy.FtoC([ f ], this.myDel)</em>
            Debug.write('Invoking FtoC...');
        &lt;/method&gt;

        &lt;method name="myhandler" args="data"&gt;
            Debug.write('got data:', data);
        &lt;/method&gt;

    &lt;/button&gt;

&lt;/canvas&gt;
</example>

<p>Alternatively, you can use remotecall for a more declarative approach to
invoking functions. See the remotecall reference or the RPC chapter of the
Developer's Guide for more information.</p>

<example title="Invoking remote function using remotecall">
&lt;canvas debug="true" height="280"&gt;

    &lt;debug x="10" y="40" width="470" height="230" /&gt;

    &lt;soap name="temperature" autoload="false"
          wsdl="http://developerdays.com/cgi-bin/tempconverter.exe/wsdl/ITempConverter"&gt;

        &lt;method name="init"&gt;
            super.init();
            Debug.write('soap service loading...');
            this.load();
        &lt;/method&gt;

        &lt;method event="onload"&gt;
            Debug.write('temperature service loaded!');
            Debug.write('---');

            // don't allow others to call RPC object until proxy is loaded.
            canvas.convert.setVisible(true);
        &lt;/method&gt;

        <em>&lt;remotecall funcname="FtoC"&gt;</em>
            <em>&lt;param value="100" /&gt;</em>

            &lt;method event="ondata" args="value"&gt;
                Debug.write('got data:', value);
            &lt;/method&gt;
            &lt;method event="onerror" args="errmsg"&gt;
                Debug.write('error:', errmsg);
            &lt;/method&gt;

        <em>&lt;/remotecall&gt;</em>

    &lt;/soap&gt;

    &lt;button name="convert" text="convert" x="10" y="10" visible="false"&gt;
        &lt;method event="onclick"&gt;
            <em>canvas.temperature.FtoC.invoke();</em>
            Debug.write('Invoking FtoC...');
        &lt;/method&gt;
    &lt;/button&gt;

&lt;/canvas&gt;
</example>

<seealso>
<classes><a href="${reference}javarpc.html">javarpc</a></classes>
<classes><a href="${reference}soap.html">soap</a></classes>
<classes><a href="${reference}xmlrpc.html">xmlrpc</a></classes>
<classes><a href="${reference}remotecall.html">remotecall</a></classes>
<a href="${dguide}rpc.html">Developer's Guide: RPC chapter</a>
<a href="${dguide}rpc-javarpc.html">Developer's Guide: JavaRPC chapter</a>
<a href="${dguide}rpc-soap.html">Developer's Guide: SOAP chapter</a>
<a href="${dguide}rpc-xmlrpc.html">Developer's Guide: XML-RPC chapter</a>
</seealso>

</body>
</html>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2001-2004 Laszlo Systems, Inc.  All Rights Reserved.              *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->
